TDL and the Toolbox

Overview	
The TDL (Toolbox Definition Language) compiler enables new Toolbox traps to be added to the Development System.
In most cases it will not be necessary to call the Macintosh Toolbox interface to achieve your goals within Crimson Basic, as most high level functions are performed automatically by the language.

What are Toolbox Calls ?	
Toolbox Calls are a low level interface to Operating System functions within the Macintosh Operating System.
Traditionally, when using a language such as 'C', the only way to build GUI interfaces was to use the Toolbox interface directly, which is tedious and error prone.
Having said this, advanced programmers may wish to use this interface to access low level functions which are not available within Crimson Basic. Hence the TDL Compiler is included for completeness.

Understanding TDL	
Toolbox Traps are defined in the 'ToolBoxTraps' file within the TDL folder. A Toolbox call definition is expressed as a number of parameters :

Name
The name of the ToolBox call.

Trap
The hexadecimal representation of the 'A' Trap by which the Operating System understands the Trap.

Type
Toolbox Traps fall into two categories :
    Register based (R), where the parameters are passed in processor registers.
    Stack based (S), where the parameters are passed on the stack.

Inparm
Describes the input parameters to the Toolbox call in terms of Basic data types. These are:

For Type='S' (Stack Based)
  I    - Integer (any 32 bit value, including Pointers and Handles).
  W   - Word (any 16 bit value)
  B    - Byte (any 8 bit value)
  P    - Pascal String (data type Str255)
  T    - Data in a Structure
  C    - A fixed length character string (data type Char)

For Type='R' (Register based)
  A0  - the A0 register
  D0  - the D0 register

Outparm
Describes the output parameters from the Toolbox call.
The data types are the same as for Inparm.

SelType (optional)
Some Toolbox calls have the same Trap number and use a Selector to distinguish between them :  
  R  - Register based
  S  - Stack based

Selector (optional)
The numeric Selector required to complete the ToolBox call definition.

Sources of Information	
Anyone interested in studying the Toolbox calls available within the Macintosh Operating System (not for the faint hearted) should refer to the 'Inside Macintosh' documentation (downloadable for free) at the Apple Web site:
http://devworld.apple.com/dev/insidemac.shtml
The volumes of most interest are :
    Toolbox Essentials,
    More Macintosh Toolbox,
    Memory.

Using TDL	
 The ToolBoxTraps file provided contains most of the commonly used Toolbox Traps and these are already available for use within Crimson Basic.
A Toolbox trap is coded like any other call to a Procedure or Function except that the Name of the Trap is preceded by a "_" character. For example.

To allocate a handle to an area of memory :
    Global Handle As Integer
    Handle=_NewHandle(666)  ..  will allocate a handle to a new area of memory of
                                               666 bytes.

    Global WinPtr As Integer
    Global WinTitle As Str255[255]
        _SetWTitle(WinPtr,WinTitle)  ..  will change a Windows Title

Don't be put off by the complexity of TDL, its well worth the effort to study this low level interface if you're interested in getting into the 'bowels' of the Mac Operating System.